Using the Message Cleanup Functions(IM:XP)

Inside Macintosh: QuickDraw GX Printing Extensions and Drivers /: Chapter 5 - Printing Functions for Message Overrides / Using the Printing Functions

Using the Message Cleanup Functions
When you override a message in your printing extension or printer driver, you often forward the message to other message handlers so that they can add their operations to the execution of the message.
Some QuickDraw GX message handlers allocate storage or modify state variables in response to certain printing messages. If something goes wrong in the processing of those messages, these handlers need to reverse their actions. The messages that require this reversing of actions, or cleanup, are the GXOpenConnection, GXStartJob, GXStartPage, and GXStartSendPage messages, which are described in the chapter "Printing Messages" in this book.
If you forward one of these messages from within your override code and then detect an error, you need to call the cleanup function. Each cleanup function sends a cleanup message to the handlers, starting with the handler immediately below your extension or driver in the chain. This ensures that each handler receives the message only once and in the appropriate order. The cleanup functions are: GXCleanupOpenConnection, GXCleanupStartJob, GXCleanupStartPage, and CleanupGXStartSendPage.
Listing 5-4 shows the ImageWriter II printer driver override of the GXOpenConnection message. This code uses the nrequire macro for exception handling and calls the GXCleanupOpenConnection function if an error occurs during the processing of the GXOpenConnection message. The nrequire macro is described in the chapter "Printer Drivers" in this book.
Listing 5-4 Calling the GXCleanupOpenConnection function
OSErr SD_OpenConnection(void)
{
   OSErr    anErr;
   
   
   /* first, open the connection the standard way */
   anErr = Forward_GXOpenConnection();
   nrequire(anErr, GXOpenConnection);
   
   /* then, bring the configuration file up to date */
   anErr = UpdateConfiguration();
   nrequire(anErr, UpdateConfiguration);
      
   return(noErr);
   
/* exception handling */
UpdateConfiguration: 
   GXCleanupOpenConnection();
   
GXOpenConnection:

   return(anErr);
   
}
If an error occurs during the execution of the GXOpenConnection message, this override function calls the GXCleanupOpenConnection function.